EnigmA Amiga Run 1997 May

home *** CD-ROM | disk | FTP | other *** search

/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / earcd / dev / misc / ros_v2_1.lha / ros.doc < prev next >

Wrap

Text File | 1997-01-20 | 75KB | 1,900 lines

TABLE OF CONTENTS ros.library/--Overview-- ros.library/--History-- ros.library/ROSAddTimerInt ros.library/ROSAllocAudio ros.library/ROSAllocMem ros.library/ROSAwakeSystem ros.library/ROSChipsetCheck ros.library/ROSCPUCheck ros.library/ROSCPUClock ros.library/ROSDeleteFile ros.library/ROSDisableReq ros.library/ROSDiskLoad ros.library/ROSDiskState ros.library/ROSEnableReq ros.library/ROSFreeAudio ros.library/ROSFreeMem ros.library/ROSGetDMA ros.library/ROSGetInt ros.library/ROSGetKey ros.library/ROSKillSystem ros.library/ROSQueryKeys ros.library/ROSReadExe ros.library/ROSReadFile ros.library/ROSReadJoyPort ros.library/ROSRemTimerInt ros.library/ROSRequester ros.library/ROSScreenToBack ros.library/ROSScreenToFront ros.library/ROSSetCache ros.library/ROSSetCopper ros.library/ROSSetDMA ros.library/ROSSetExitHandler ros.library/ROSSetInt ros.library/ROSSetIntVec ros.library/ROSSetJoyPortAttrs ros.library/ROSSetTimerVec ros.library/ROSStartTimer ros.library/ROSStopTimer ros.library/ROSSysCall ros.library/ROSSysCallEnd ros.library/ROSWaitVBlank ros.library/ROSWriteFile ros.library/--Overview-- ros.library/--Overview-- This section describes the way how to use the RETIRE Operating System within your own applications: The ros.library is an enhanced lowlevel.library. It's compatible with currently all available machines and CPU's (upto '060) and OS1.3 compatible too! The ROS provides additional functions to take over the entire system so it should be useful for demo & game coders. Another advantage is the ability to call important system functions (memory allocation, read, write) from a killed system. ROS offers a way to run your hardware bashing application within multitasking. And finally a ROS prefs file is provided to support custom settings. On startup ROS tries to load the ros.prefs from your ENV: directory. You may edit this file to configure the library for your needs. But remember: It's impossible to open the ros.library from two applications at the same time. The second application will fail to open the library! Programming guidelines: The ros.library is a standard Amiga library so normal restrictions applies to function calls: - a6 loaded with _ROSBase - d0/d1/a0/a1 scratch registers (destroyed by libcall) - functions can't be called from within interrupts Some ROS functions are special in these cases; they need no scratch registers or they may be called from within interrupts. Look at the appropriate 'note' comment for further information. Do not call any ROS function from supervisor mode. The machine will crash!!! I think there is no need to switch to supervisor mode. Think of the '060 CPU; its supervisor model differs from the '040 CPU and a few basic commands will be emulated by software. Executing such a command from supervisor mode may crash the machine!!! Call ROSKillSystem(ROSKSF_DEATHMODE) to take over the entire system. But do not modify DMA & interrupt stuff by yourself! Use the appropriate ROS routines!!!!! ROSKillSystem() opens a PAL-LowRes screen so all 'special' AGA registers are flushed (FMODE & sprites may not!?!) and it forces graphics boards to switch to the Amiga custom chip display. With ROS V2 I introduce a new os-friendly mode. From now there are 4 possible methods killing the system: - ROSKillSystem(ROSKSF_DEATHMODE): Here you may trash all display related registers. You may also use the blitter. It is owned by ROS so do not use OwnBlitter(). But remember: If you call a ROS function which may interrupt the deathmode with ROSSysCall() you should finish all your blits before entering this function (because the OS needs his blitter!). ROS V2 uses a waitblit before entering any system function so the only thing you have to do is to suppress all blits in your interrupt code until the called function returns. - ROSKillSystem(ROSKSF_SYSMODE): Here is the system active but ROS opens a PAL-LowRes screen like in the deathmode. This means real multitasking, screen switching, and so on. That's why you shouldn't use the blitter. If you need it you have to call OwnBlitter()/DisownBlitter(), but remember: The Amiga OS relies on his blitter! Never allocate it for long times, the system may run in a deadlock state!!! In the sysmode you may trash all display related registers only if ROS screen in front (preferably via copper). - ROSKillSystem(ROSKSF_DEATHMODE|ROSKSF_OSFRIENDLY), new for ROS V2: This is an system-friendly deathmode. ROS opens a screen according to the supplied taglist. All input events are catched by ROS and your taskpriority is raised to the input.device's priority for maximum performance. Screen switching is disabled so you do not call system functions which may depth-arrange screens -> result is a deadlock! Now you do NOT trash any display related custom registers, use system calls for screen manipulation. ROSSetCopper() and ROSSetDMA() have no effect, use OS calls! - ROSKillSystem(ROSKSF_SYSMODE|ROSKSF_OSFRIENDLY), new for ROS V2: This is the system-friendly sysmode?!? ROS opens a screen according to the supplied taglist. Multitasking and screen switching are active. Do NOT trash any display related custom registers, use system calls. ROSSetCopper() and ROSSetDMA() have no effect! In all modes above you may trash the audio custom chip registers and the CIA registers if successfully allocated via appropriate ROS calls! You should never touch the following: - DMACON and INTENA registers - CIA ICR registers - CPU interrupt vectors - serial registers - disk related registers Tips 'n' hints for using ROS: In a multitasking environment your vblank code may be called after the display is started depending on the speed of higher prioritized vblank interrupts. If you want to synchronize custom chip modifications with the display you should use the copper. And remember: The vblank frequency may vary (not always 50 Hz) if ROS screen behind other screens or if os-friendly mode! Some words about the ROS file functions: First of all avoid these SENSELESS disk assigns. Since OS2.0 it's possible to load additional data files relativ to your programm directory by using a filename like this "progdir:data1". Use it!!! On OS1.3 ROS removes the "progdir:" prefix automatically from your supplied filename, so the only thing the user have to do is a "CD" to the programm directory before starting your application! Another ROS feature is the "disk waiting". That means if you load files from disk (providing the ROSRWF_DISKWAIT flag and a filename like "Disk1:data1") ROS is waiting for the right disk to be inserted. Prior to ROS V2 this disk-wait can't be cancelled (see also ROSDiskState()). Please read the following docs carefully! If you have questions, problems, idea's or bug reports feel free to contact me: TIK/RETIRE via email: Nico.Schmidt@Student.Uni-Magdeburg.de or write to: Nico Schmidt Möhlauer Str. 9 06773 Jüdenberg GERMANY Thanks to: TODI/RETIRE for hints and useful idea's PABLO/RETIRE for beta testing Christian Oldiges for testing, hints & bug reports ros.library/--History-- ros.library/--History-- ROS HISTORY ******************************************************************************* RELEASE 1.0, 29.12.95 (Library version 1.0) The first release. ******************************************************************************* RELEASE 1.1, 05.01.96 (Library version 1.1) Fixed two minor bugs: - ROSCPUClock() shouldn't display a requester if no free CIA available, but it does - user vblank code was called from vblank server with priority 9, this may confuse the timer.device (priority 0) and thus all CIA interrupts (e.g. level6 p61) if it steals to much rastertime; now user vblank code is executed from a priority 0 vblank server ******************************************************************************* RELEASE 1.2, 08.01.96 (Library version 1.2) Library name changed from 'ROS.library' to 'ros.library' because a library name should always be a lower-case string (thanks to Thomas Kessler) ******************************************************************************* RELEASE 1.21, 05.02.96 (Library version 1.2) P61 initialization bug fixed (wrong offset if 020 optimization), thanks to PABLO/RETIRE ******************************************************************************* RELEASE 2.0, 01.11.96 (Library version 2.0) Minor bug fixes: - ROSOpenScreen() changed the forbidden state on retry, now fixed - ROSWaitVBlank() now uses graphics/WaitTOF() in non-deathmode - ROSSetCache() always enables the data cache on 68060, seems to be a problem in 68060.library CacheControl() patch, now a workaround added - Some errors fixed in this autodoc Changes: - ROSChipsetCheck() examines gfxbase on OS3.0 instead of reading the Alice/Lise ID chip registers - CIA allocation rewritten, now ROS should run without CIA hardware if you don't need a timer - WaitBlits added in ROSKillSystem()/ROSAwakeSystem() & ROSSysCall()/ ROSSysCallEnd() functions New features: - New os-friendly mode for ROSKillSystem() added to support standard OS screens for e.g. CyberGraphics applications - Joyport routines ROSReadJoyPort()/ROSSetJoyPortAttrs() added - ROSDiskLoad()/ROSDiskState() added - Now the user may disable audio allocation via ros.prefs - Joy/mouse buttons may act as exit keys (see ROSSetJoyPortAttrs()) ******************************************************************************* RELEASE 2.1, 21.01.97 (Library version 2.1) Minor bug fixes: - Credits requester wasn't font-sensitive on OS1.3 - Accessing "progdir:"-relative files using ROS r/w functions did not work on OS1.3, wrong string comparison (thanks to Christian Oldiges) - Some errors fixed in this autodoc Changes: - ROSCPUClock() now uses timer.device if there are no free cia timers ******************************************************************************* ros.library/ROSAddTimerInt ros.library/ROSAddTimerInt NAME ROSAddTimerInt -- add an interrupt that is executed at regular intervals SYNOPSIS intHandle = ROSAddTimerInt(Flags, intRoutine); D0 D0 A0 ULONG AddTimerInt(ULONG, APTR); FUNCTION Calling this routine causes the system to allocate a CIA timer depending on 'Flags' and set up 'intRoutine' to service any interrupts caused by the timer. Although the timer is allocated it is neither running, nor enabled. ROSStartTimer() must be called to establish the time interval and start the timer. The routine is called from within an interrupt, so normal restrictions apply. On entry A5 holds the custom base ($dff000) and A6 holds _ROSBase. Your code may trash all registers. The CIA timer used by this routine is not guaranteed to always be the same. This routine utilizes the CIA resource and uses an unallocated CIA timer. You should remove the timer with ROSRemTimerInt(). Closing the ros.library removes this timer interrupt automatically. INPUTS Flags - specify the timer to allocate: TIMF_ANY - try to allocate any timer TIMF_LEV2 - try to allocate level 2 timers (CIA A) TIMF_LEV6 - try to allocate level 6 timers (CIA B) intRoutine - the routine to invoke upon timer interrupts. RESULT intHandle - a handle used to manipulate the interrupt, or NULL if it was not possible to attach the routine. NOTE If allocation failed a Retry/Cancel-Requester appears to inform the user about the problem (if not suppressed and if not in deathmode). This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSRemTimerInt(), ROSStartTimer(), ROSStopTimer(), ROSSetTimerVec() ros.library/ROSAllocAudio ros.library/ROSAllocAudio NAME ROSAllocAudio -- allocate audio channels SYNOPSIS success = ROSAllocAudio() D0 BOOL ROSAllocAudio(VOID); FUNCTION This function allocates all audio channels. Audio DMA is updated so that matches with current DMA settings (former ROSSetDMA() calls). --> New for V2: The user may disable audio allocation via ros.prefs! You should free the audio channels with ROSFreeAudio(). Closing the ros.library frees audio channels automatically. RESULT success - boolean NOTE If allocation failed a Retry/Cancel-Requester appears to inform the user about the problem (if not suppressed and if not in deathmode). This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSFreeAudio() ros.library/ROSAllocMem ros.library/ROSAllocMem NAME ROSAllocMem -- allocate memory and keep track of the size SYNOPSIS memoryBlock = ROSAllocMem(byteSize, attributes, alignmask) D0 D0 D1 D2 VOID *ROSAllocMem(ULONG, ULONG, ULONG); FUNCTION This function works identically to Exec's AllocMem(), but tracks the size of the allocation and provides additional memory alignment. See the AllocMem() documentation for details. You should free the memory with ROSFreeMem(). Do NOT use exec.library functions!!!!!!! Closing the ros.library frees allocated memory automatically. INPUTS byteSize - # of bytes to allocate attributes - memory requirements alignmask - used to allocate memory at special boundaries, if NULL Exec's standard alignment applies --> newaddr = memaddr AND NOT(alignmask) e.g. mem align: even by 8 bytes -> alignmask = $00000007 RESULT memoryBlock - a pointer to the newly allocated memory block or NULL NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSFreeMem(), exec.lib/AllocMem() ros.library/ROSAwakeSystem ros.library/ROSAwakeSystem NAME ROSAwakeSystem -- close ROS screen and awake from deathmode SYNOPSIS ROSAwakeSystem() VOID ROSAwakeSystem(VOID); FUNCTION This function deallocates all things allocated with ROSKillSystem(). It closes the opened screen and sets the display related DMA to the appropriate system values. Calling this function without a matching ROSKillSystem() is harmless. Closing the ros.library calls automatically ROSAwakeSystem(). SEE ALSO ROSKillSystem() ros.library/ROSChipsetCheck ros.library/ROSChipsetCheck NAME ROSChipsetCheck -- check if desired custom chipset available SYNOPSIS result = ROSChipsetCheck(chipsetbit) D0 D0 UWORD ROSChipsetCheck(UWORD); FUNCTION Use this routine to obtain the available chipset. As input you may specify the chipset requirement (bitnumber) and if NOT found a requester appears to inform the user about his lack of hardware (if not suppressed and if not in deathmode). INPUTS chipsetbit - the required chipset; currently defined are ROSCSB_ECS for at least HR-AGNUS rev3 and 8373 DENISE ROSCSB_AGA for at least ALICE rev2 and LISA, or -1 for only obtaining chipset (no requester appears) RESULT result - chipset flags (ROSCF_xxx, AGA includes the ECS flag) or NULL if required chipset not found ros.library/ROSCPUCheck ros.library/ROSCPUCheck NAME ROSCPUCheck -- check if desired CPU/FPU available SYNOPSIS result = ROSCPUCheck(cpubit) D0 D0 UWORD ROSCPUCheck(UWORD); FUNCTION Use this routine to obtain the available CPU/FPU. As input you may specify the processor requirement (bitnumber) and if NOT found a requester appears to inform the user about his hardware problem (if not suppressed and if not in deathmode). Call this routine twice if you need a CPU (AFB_680x0) check and a FPU (AFB_6888x/FPU40) check. INPUTS cpubit - the required CPU/FPU -> AttnFlags AFB_xxxxx or -1 for only obtaining CPU/FPU (no requester appears) RESULT result - AttnFlags or NULL if required chipset not found NOTE This code handles the FPU40 flag correct: it's only valid if AFB_68040 set. Keep this in mind if you examine the RESULT (AttnFlags)!!! ros.library/ROSCPUClock ros.library/ROSCPUClock NAME ROSCPUClock -- CPU/FPU clock calculation SYNOPSIS CPU/FPUclock = ROSCPUClock() D0 D1 ULONG/ULONG ROSCPUClock(VOID); FUNCTION Calculate CPU/FPU clock. The values returned should be accurate at least 1/10 MHz, so it's enough for everyone. This routine tries to allocate a cia timer. On failure the timer.device is used (only on OS2.0+) which is less accurate so it's best to call this routine first (e.g. before any timer function). ROSCPUClock() works with all (currently) available processors and it takes only a few milliseconds!!! RESULT CPUclock - the CPU clock in kHz or NULL on error (see also BUGS) FPUclock - the FPU clock in kHz or NULL on error NOTE This function interrupts the deathmode state with ROSSysCall()! BUGS In some rare cases the function returns NULL: - Allocation problems (cia timers, timer.device) - on 68000/10 with only chipmem - on _really_ slow machines (e.g. a 10MHz 68040?!?) - on 68040/60 systems where it's impossible to turn on instruction cache (e.g. A4000 with only chipmem and 68040.library loaded) The FPU clock is ALWAYS NULL for 68881/2 systems because I'm (currently) unable to find a reliable algorithm (blame on me). It's hard to deal with the asynchronous data transfer between CPU and FPU. On 68040/60 systems with FPU the returned value is the same like CPU clock. ros.library/ROSDeleteFile ros.library/ROSDeleteFile NAME ROSDeleteFile -- Delete a file or directory SYNOPSIS success = ROSDeleteFile(flags, name) D0 D0 A0 ULONG ROSDeleteFile(ULONG, STRPTR); FUNCTION This attempts to delete the file or directory specified by 'name'. Note that all the files within a directory must be deleted before the directory itself can be deleted. If ROSRWF_DISKWAIT flag set the routine assumes that you want to delete 'name' from a floppy. This means: - waiting for the right disk to be inserted (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK, NO_DISK force retry until any other error occurs) --> New for V2: waiting may be cancelled via ROSDiskState() - waiting until disk drive stopped (implementation: polling disk.resource until drives are ready) Since OS2.0 it's possible to delete files from your program path instead of the current directory using progdir:xxx. On OS1.3 the "progdir:" string is automatically removed by ROS so you don't have to worry about it. The only thing the user have to do is a "CD" to the program directory before starting (only on OS1.3). ;-) WARNING: It may be dangerous to use this routine within deathmode! Because of the AMIGA's multitasking facilities it isn't possible (isn't it???) to wait till the final end of a delete operation. That's why I use a simple delay of 2 seconds after any delete operation in deathmode. If your filesystem is to slow to write all the data within this time your partition will be NOT validated!!! You've been warned!!! INPUTS flags - use ROSRWF_DISKWAIT if you want to delete from a floppy name - pointer to a null-terminated string RESULT success - DOS error code on failure or NULL for success NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO dos.lib/DeleteFile(), ROSDiskState() ros.library/ROSDisableReq ros.library/ROSDisableReq NAME ROSDisableReq -- suspend requesters for our task SYNOPSIS ROSDisableReq() VOID ROSDisableReq(VOID); FUNCTION Suspend all upcoming requesters for our task (ROS- and DOS-Requesters). By default requesters are enabled. SEE ALSO ROSEnableReq(), ROSRequester() ros.library/ROSDiskLoad ros.library/ROSDiskLoad NAME ROSDiskLoad -- returns whether your program loaded from disk (V2) SYNOPSIS result = ROSDiskLoad(diskname) D0 A0 BOOL ROSDiskLoad(STRPTR); FUNCTION Returns whether your program loaded from a disk labeled 'diskname' or not. Therefore you have to pass the name of your disk to this function. After this you should set the flags of all subsequent read/write calls according to the result (e.g. ROSReadFile(ROSRWF_DISKWAIT, ...) if the result was TRUE)! Implementation: This function compares the 'diskname' with the name of the disk where the home dir of your program (on OS1.3 the current dir) is located. If both strings are equal (case-insensitive) this function returns TRUE. Whenever locale.library is installed in your system, the string comparision is replaced by language-specific code. INPUTS diskname - name of the disk RESULT result - TRUE if your program loaded from a disk labeled 'diskname' NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSDeleteFile(), ROSReadExe(), ROSReadFile(), ROSWriteFile() ros.library/ROSDiskState ros.library/ROSDiskState NAME ROSDiskState -- return state of current disk operation (V2) SYNOPSIS state = ROSDiskState(diskbreak) D0 D0 UWORD ROSDiskState(BOOL); FUNCTION This function is used to determine the state of the current disk operation. Therefore it's save to call this function from within interrupts. Set 'diskbreak' TRUE for cancelling the 'wait for disk'-state of current disk operation. In this case the current disk operation returns with one of the following DOS error codes: DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK or NO_DISK. INPUTS diskbreak - TRUE for cancelling the 'wait for disk'-state RESULT state - the state of the current disk operation (defines from ros.i): DISK_NOP currently no disk operation, 'diskbreak' has no effect DISK_Init initialize (check for disk) in progress DISK_Waiting ROS is waiting for the (right) disk to be inserted, cancel this with 'diskbreak'=TRUE DISK_Busy read/write/delete in progress NOTE This call is guaranteed to preserve all registers and is save to call from interrupts. SEE ALSO ROSDeleteFile(), ROSReadExe(), ROSReadFile(), ROSWriteFile() ros.library/ROSEnableReq ros.library/ROSEnableReq NAME ROSEnableReq -- permit requesters for our task SYNOPSIS ROSEnableReq() VOID ROSEnableReq(VOID); FUNCTION Permit all upcoming requesters for our task (ROS- and DOS-Requesters). By default requesters are enabled. SEE ALSO ROSDisableReq(), ROSRequester() ros.library/ROSFreeAudio ros.library/ROSFreeAudio NAME ROSFreeAudio -- free audio channels SYNOPSIS ROSFreeAudio() VOID ROSFreeAudio(VOID); FUNCTION This function removes probably installed audio interrupt handlers and resets the audio DMA (former system values). Then channels are freed. Freeing channels without allocation is harmless. Closing the ros.library frees audio channels automatically. NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSAllocAudio() ros.library/ROSFreeMem ros.library/ROSFreeMem NAME ROSFreeMem -- return allocated memory to the system SYNOPSIS ROSFreeMem(memoryBlock) A0 VOID ROSFreeMem(VOID *); FUNCTION Free an allocation made by the ROSAllocMem() call. The memory will be returned to the system pool from which it came. WARNING: Before freeing some chip memory be sure that the blitter has finished its work within this memory block!!! The same applies to closing the ros.library. Closing the ros.library frees allocated memory automatically. NOTE Passing a wrong pointer is harmless ;-) This function interrupts the deathmode state with ROSSysCall()! INPUTS memoryBlock - pointer to the memory block to free, or NULL SEE ALSO ROSAllocMem() ros.library/ROSGetDMA ros.library/ROSGetDMA NAME ROSGetDMA -- obtain DMA settings SYNOPSIS DMACONR = ROSGetDMA() D0 UWORD ROSGetDMA(VOID); FUNCTION This function returns current DMA settings (set via ROSSetDMA()). Do NOT use "move.w $dff002,d0" !!!!!!! This may return wrong bits if you are in non-deathmode (e.g. copper DMA -> the OS may change the bit during screen switching). But ROSGetDMA() returns the right value. Closing the ros.library reset former system DMA. RESULT DMACONR - DMA settings set via ROSSetDMA() with additional BBUSY/BZERO bits (unsupported (disk) & unallocated (audio, ...) DMA bits are always 0) NOTE This call is guaranteed to preserve all other registers and is save to call from interrupts. SEE ALSO ROSSetDMA() ros.library/ROSGetInt ros.library/ROSGetInt NAME ROSGetInt -- obtain interrupt settings SYNOPSIS INTENAR = ROSGetInt() D0 UWORD ROSGetInt(VOID); FUNCTION This function returns interrupt enable bits (set via ROSSetDMA()). Additional bits are defined in "ros.i". Do NOT use "move.w $dff01c,d0" !!!!!!! This may return wrong bits. Closing the ros.library reset former system interrupt bits. RESULT INTENAR - Interrupt bits set via ROSSetInt() Note: level 1/2/5/6 bits (disk, serial, timer) are not supported!!! Instead additonal bits are defined: - KEYB - CIAATIMA/B - CIABTIMA/B NOTE This call is guaranteed to preserve all other registers and is save to call from interrupts. SEE ALSO ROSSetInt(), libraries/ros.i ros.library/ROSGetKey ros.library/ROSGetKey NAME ROSGetKey -- returns the currently pressed rawkey code and qualifiers SYNOPSIS key = ROSGetKey() D0 ULONG ROSGetKey(VOID); FUNCTION This function returns the currently pressed non-qualifier key and all pressed qualifiers. The values returned by this function are not modified by which window/screen currently has input focus. RESULT key - key code for the last non-qualifier key pressed in the low order word ($0..$67). If no key is pressed this word will be $ff. The upper order word contains the qualifiers which can be found within the long word as follows (lowlevel.library like): Qualifier Key LLKB_LSHIFT Left Shift LLKB_RSHIFT Rigt Shift LLKB_CAPSLOCK Caps Lock LLKB_CONTROL Control LLKB_LALT Left Alt LLKB_RALT Right Alt LLKB_LAMIGA Left Amiga LLKB_RAMIGA Right Amiga NOTE This call is guaranteed to preserve all other registers and is save to call from interrupts. SEE ALSO lowlevel.lib/GetKey(), libraries/lowlevel.i ros.library/ROSKillSystem ros.library/ROSKillSystem NAME ROSKillSystem -- kill the system and open ROS screen SYNOPSIS success = ROSKillSystem(mode, taglist) D0 D0 A0 BOOL/struct Screen *ROSKillSystem(ULONG, struct TagItem *); FUNCTION Depending on the mode this function acts different: In non-os-friendly mode this function opens a PAL-LowRes screen, installs your copper list and sets additional DMA (copper, bitplane, sprite). By default all DMA will be cleared. Whenever this screen is the frontmost you may bash all display related custom chip registers (preferably via copper list). If the ROS is unable to open the screen or if it's not PAL-LowRes (promoted screen) a Retry/Cancel-Requester appears (if not suppressed). If you specify the flag KILLF_DEATHMODE the multitasking will be turned off. Now ROS has taken over the entire system. But interrupts and DMA should only be set with ROS functions!!! The blitter is owned via OwnBlitter() so you may use it. But before using you should do a WaitBlit because it may still working, --> this is now obsolete with ROS V2. You may interrupt the deathmode via ROSSysCall(). At this time the blitter will be disowned so you do NOT use it during a SysCall!!! Call ROSKillSystem() with KILLF_SYSMODE to run your application within multitasking. But be polite and bash the hardware as less as possible. The blitter is under system control so you should use OwnBlitter()/ DisownBlitter() if you need it. But allocate the blitter only for a short time because the system uses it too! With ROS V2 we introduce a new os-friendly mode. From now it's possible to use the death/sysmode with a standard OS screen by passing the appropriate taglist to this function. NO MORE HARDWARE BASHING!!! Use OS calls for screen rendering! You have to clear the mouse pointer with OS calls too! (look at --Overview-- for further details) This feature works only on OS2.0+. Setting this flag on OS1.3 this call fails with "Couldn't open OS2.0 screen" error. Note: Do not make this screen public because ROS captures most rawkey events (see also ROSSetIntVec()/KEYB-Int) so applications opened on ROS screen will never receive it. The os-friendly mode should be used to provide compatibility with e.g. CyberGraphics! Also check out the ROS_KillSysFlags (the current ROS state). You may call ROSKillSystem() multiple times to switch between death- and sysmode, but calling again the KILLF_OSFRIENDLY flag has NO effect. To swith between os-friendly and bashmode you have to call first ROSAwakeSystem() to close the current ROS screen and after that call ROSKillSystem() to re-open the screen. A switch from sysmode into deathmode automatically makes the ROS screen the frontmost so you don't have to call ROSScreenToFront(). Once ROSKillSystem() returns successful further calls to this function will never fail so there is no need to check the result again. You should return to the system with ROSAwakeSystem(). Closing the ros.library calls ROSAwakeSystem() automatically. INPUTS mode - KILLF_SYSMODE for a multitasking environment KILLF_DEATHMODE to take over the entire system --> New for V2: KILLF_OSFRIENDLY for os-friendly mode, use it in conjunction with one of the flags above (not supported if ROS runs on OS1.3, ROSKillSystem() will fail) taglist - ptr to taglist passed to OpenScreen(), only neccessary if KILLF_OSFRIENDLY RESULT success - result type depends on the KILLF_OSFRIENDLY flag: if flag set (ROS V2): ptr to ROS screen or NULL on failure if flag not set: FALSE if ROS was unable to open the PAL-LowRes screen, else TRUE SEE ALSO ROSAwakeSystem(), ROSSysCall(), ROSSysCallEnd() ros.library/ROSQueryKeys ros.library/ROSQueryKeys NAME ROSQueryKeys -- return the states for a set of keys SYNOPSIS ROSQueryKeys(queryArray, arraySize) A0 D0 VOID ROSQueryKeys(struct KeyQuery *, UBYTE); FUNCTION Scans the keyboard to determine which of the rawkey codes listed in the 'queryArray' are currently pressed. The state for each key is returned in the array. The values returned by this function are not modified by which window/screen currently has input focus. INPUTS queryArray - an array of KeyQuery structures. The kq_KeyCode fields of these structures should be filled with the rawkey codes you wish to query about. Upon return from this function, the kq_Pressed field of these structures will be set to TRUE if the associated key is down, and FALSE if not. arraySize - number of key code entries in 'queryArray' NOTE This function is save to call from interrupts. SEE ALSO lowlevel.lib/QueryKeys(), libraries/lowlevel.i ros.library/ROSReadExe ros.library/ROSReadExe NAME ROSReadExe -- scatterload a loadable file SYNOPSIS seglist/errorcode = ROSReadExe(flags, name) D0 D1 D0 A0 BPTR/ULONG ROSReadExe(ULONG, STRPTR); FUNCTION This function tries to scatterload the file 'name' using dos.library's LoadSeg(). If ROSRWF_DISKWAIT flag set the routine assumes that you want to load 'name' from a floppy. This means: - waiting for the right disk to be inserted (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK, NO_DISK force retry until any other error occurs) --> New for V2: waiting may be cancelled via ROSDiskState() - waiting until disk drive stopped (implementation: polling disk.resource until drives are ready) Since OS2.0 it's possible to load files from your program path instead of the current directory using progdir:xxx. On OS1.3 the "progdir:" string is automatically removed by ROS so you don't have to worry about it. The only thing the user have to do is a "CD" to the program directory before starting (only on OS1.3). ;-) You should unload the file with ROSFreeMem(seglist)! Do NOT use dos.library's UnLoadSeg()!!!!!!! Closing the ros.library unloads file automatically. INPUTS flags - use ROSRWF_DISKWAIT if you want to load from a floppy name - pointer to a null-terminated string RESULT seglist - BCPL pointer to a seglist or NULL if error errorcode - DOS error code on failure (may be NULL!!!) NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSDiskState(), ROSFreeMem(), dos.lib/LoadSeg() ros.library/ROSReadFile ros.library/ROSReadFile NAME ROSReadFile -- read a number bytes from a file SYNOPSIS actLength/errorcode/actBuffer = ROSReadFile(flags, length, offset, D0 D1 A0 D0 D1 D2 memtype, memalign, name, buffer) D3 D4 A0 A1 ULONG/ULONG/VOID * ROSReadFile(ULONG, ULONG, ULONG, ULONG, ULONG, STRPTR, VOID *); FUNCTION This function tries to load 'length' bytes from the file 'name' using dos.library's Read(). Set 'length` = 0 to load the whole file. A1 points to a buffer where the data should be placed, or set A1=0 to force an automatic memory allocation. In this case you must specify 'memtype' and 'memalign' (see also ROSAllocMem()). If ROSRWF_DISKWAIT flag set the routine assumes that you want to load 'name' from a floppy. This means: - waiting for the right disk to be inserted (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK, NO_DISK force retry until any other error occurs) --> New for V2: waiting may be cancelled via ROSDiskState() - waiting until disk drive stopped (implementation: polling disk.resource until drives are ready) Since OS2.0 it's possible to load files from your program path instead of the current directory using progdir:xxx. On OS1.3 the "progdir:" string is automatically removed by ROS so you don't have to worry about it. The only thing the user have to do is a "CD" to the program directory before starting (only on OS1.3). ;-) You should free the automatically allocated memory with ROSFreeMem()! Closing the ros.library unloads file automatically (if automatic memory allocation). INPUTS flags - use ROSRWF_DISKWAIT if you want to load from a floppy length - number of bytes to load or NULL for the whole file offset - number of bytes to skip before reading from file memtype - see ROSAllocMem(), only neccessary if 'buffer' == NULL memalign - see ROSAllocMem(), only neccessary if 'buffer' == NULL name - pointer to a null-terminated string buffer - pointer to buffer or NULL to force an automitic memory allocation RESULT actLength - number of bytes read from file or -1 if error errorcode - DOS error code on failure (may be NULL!!!) actBuffer - points to loaded data, only valid on success (D0 <> -1)!!! NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSAllocMem(), ROSDiskState(), ROSFreeMem(), dos.lib/Read() ros.library/ROSReadJoyPort ros.library/ROSReadJoyPort NAME ROSReadJoyPort -- return the state of the selected joy/mouse port (V2) SYNOPSIS portState = ROSReadJoyPort(portNumber); D0 D0 ULONG ROSReadJoyPort(ULONG); FUNCTION This function is used to determine what device is attached to the joy port and the current position/button state. The user may attach a mouse, game controller, or joystick to the port and this function will dynamically detect which device is attached and return the appropriatly formatted 'portState'. This function works similar to lowlevel.lib's ReadJoyport(), so look there for further information. The only exceptions is the port assignment: port0/1 joyport as usual, but port2/3 is assigned to the parallel port, with the appropriate adapter you are able to connect two extra joysticks. Mouse and gamecontrollers are not supported by those adapters! INPUTS portNumber - port to read, in the range 0 to 3. RESULT portState - bit map that identifies the device and the current state of that device dependant on the type of device attached (like lowlevel.lib's ReadJoyPort()). The following constants from <libraries/lowlevel.h> are used to determine which device is attached and the state of that device. The type of device can be determined by applying the mask JP_TYPE_MASK to the return value and comparing the resultant value with the following: JP_TYPE_NOTAVAIL port data unavailable JP_TYPE_GAMECTLR game controller JP_TYPE_MOUSE mouse JP_TYPE_JOYSTK joystick JP_TYPE_UNKNOWN unknown device If type = JP_TYPE_GAMECTLR the bit map of portState is: JPF_BUTTON_BLUE Blue - Stop JPF_BUTTON_RED Red - Select JPF_BUTTON_YELLOW Yellow - Repeat JPF_BUTTON_GREEN Green - Shuffle JPF_BUTTON_FORWARD Charcoal - Forward JPF_BUTTON_REVERSE Charcoal - Reverse JPF_BUTTON_PLAY Grey - Play/Pause JPF_JOY_UP Up JPF_JOY_DOWN Down JPF_JOY_LEFT Left JPF_JOY_RIGHT Right If type = JP_TYPE_JOYSTK the bit map of portState is: JPF_BUTTON_BLUE Right JPF_BUTTON_RED Fire JPF_JOY_UP Up JPF_JOY_DOWN Down JPF_JOY_LEFT Left JPF_JOY_RIGHT Right If type = JP_TYPE_MOUSE the bit map of portState is: JPF_BUTTON_BLUE Right mouse JPF_BUTTON_RED Left mouse JPF_BUTTON_PLAY Middle mouse JP_MVERT_MASK Mask for vertical counter JP_MHORZ_MASK Mask for horizontal counter NOTE When called the first time, for each port, this function tries to allocate the desired port, so do NOT call this routine from interrupts until the approprite resources are allocated (return value other than JP_TYPE_NOTAVAIL, see also ROSSetJoyPortAttrs()). If allocation failed a Retry/Cancel-Requester appears to inform the user about the problem (if not suppressed and if not in deathmode) and the function will return JP_TYPE_NOTAVAIL. This function interrupts the deathmode state with ROSSysCall() when called the first time! SEE ALSO ROSSetJoyPortAttrs(), lowlevel.lib/ReadJoyPort() ros.library/ROSRemTimerInt ros.library/ROSRemTimerInt NAME ROSRemTimerInt -- remove a previously installed timer interrupt SYNOPSIS ROSRemTimerInt(intHandle); A1 VOID AddTimerInt(ULONG); FUNCTION Removes a timer interrupt routine previously installed with ROSAddTimerInt(). Closing the ros.library removes this timer interrupt automatically. INPUTS intHandle - handle obtained from ROSAddTimerInt(), if NULL nothing happens NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSAddTimerInt(), ROSStartTimer(), ROSStopTimer(), ROSSetTimerVec() ros.library/ROSRequester ros.library/ROSRequester NAME ROSRequester -- Display a requester SYNOPSIS result = ROSRequester(TextFormat, ArgList, GadgetFormat) D0 A0 A1 A2 LONG ROSRequester(STRPTR, APTR, STRPTR) FUNCTION This procedure automatically builds a requester for you using intuition's EasyRequestArgs() (AutoRequest() on OS1.3) and then waits for a response from the user. The requester appears only if it is not disabled via ROSDisableReq() or your tasks pr_WindowPtr = -1. Do not set this pointer directly. Use instead ROSDisable()/ROSEnable(). By default requesters are enabled. In deathmode requesters are always disabled. If requesters are disabled the 'result' will be always FALSE (NULL). INPUTS TextFormat - Format string, a la RawDoFmt(), for message in requester body. Lines are separated by the newline character ($0A). Formatting '%' functions are supported exactly as in RawDoFmt(). Note: on OS1.3 max 5 textlines GadgetFormat - Format string for gadgets. Text for separate gadgets is separated by '|'. You MUST specify at least one gadget. Note: max 2 gadgets on OS1.3 gadget format functions only supported on OS2.0+. argList - Arguments for format commands. Arguments for gadgets follow arguments for bodytext RESULT 0, 1, ..., N - Successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. This is for compatibility with AutoRequest(), which has FALSE for the rightmost gadget. BUGS Do not rely on the 'result' of an one-button requester! Due a bug in intuitions AutoRequest()/EasyRequestArgs() the 'result' may be TRUE (1) or FALSE (0) because it's possible to satisfy an one- button requester with both short-cuts: AMIGA-B and AMIGA-V. SEE ALSO intuition.lib/AutoRequest(), intuition.lib/EasyRequestArgs(), exec.lib/RawDoFmt(), ROSDisableReq(), ROSEnableReq() ros.library/ROSScreenToBack ros.library/ROSScreenToBack NAME ROSScreenToBack -- Send ROS screen to the back of the display SYNOPSIS ROSScreenToBack() VOID ROSScreenToBack(VOID); FUNCTION Sends the ROS screen to the back of the display if it is open and if NOT in deathmode. SEE ALSO ROSScreenToFront() ros.library/ROSScreenToFront ros.library/ROSScreenToFront NAME ROSScreenToFront -- Make ROS screen the frontmost SYNOPSIS ROSScreenToFront() VOID ROSScreenToFront(VOID); FUNCTION Brings the ROS screen to the front of the display if it is open and if NOT in deathmode. SEE ALSO ROSScreenToBack() ros.library/ROSSetCache ros.library/ROSSetCache NAME ROSSetCache -- Instruction & data cache control SYNOPSIS oldBits = ROSSetCache(cacheBits, cacheMask) D0 D0 D1 ULONG ROSSetCache(ULONG, ULONG); FUNCTION This function provides global control of any instruction or data caches that may be connected to the system. All settings are global (until ros.library closed) -- per task control is not provided. Closing the ros.library reset former system cache settings. INPUTS cacheBits - new values for the bits specified in cacheMask. use -1 to reset to system defaults (ignores cacheMask) cacheMask - a mask with ones for all bits to be changed Note: cacheBits/cacheMask may be overridden by values specified in ros.prefs (to support individual cache settings) RESULT oldBits - the complete prior values for all settings. NOTE As a side effect, this function clears all caches. This function interrupts the deathmode state with ROSSysCall()! SEE ALSO exec/execbase.i, exec.lib/CacheControl() ros.library/ROSSetCopper ros.library/ROSSetCopper NAME ROSSetCopper -- install copperlist for ROS screen SYNOPSIS ROSSetCopper(flags, coplist) D0 A0 VOID ROSSetCopper(ULONG, APTR); FUNCTION This function installs a new copper list for our ROS screen. Whenever this screen is the frontmost this copper list becomes the active (only in non-os-friedly mode!). Do NOT use "move.l #mycoplist,$dff080" or "move.w #0,$dff088" !!!!!!! This may crash the display if you are in non-deathmode and the ROS screen is not yet available or behind others. ROSSetCopper() takes this into account and displays this copper list as soon as possible. A screen switch forces always copper1 starting in a long frame! INPUTS flags - COPF_COPPER1/2: modify copper1 or copper2 Remember: copper1 is always started during vertical blank COPF_STROBE: force an immediate copper start, move.w #0,$dff088 set 'coplist' to NULL for only strobe COPF_LOF/SHF: forces a long/short frame while starting copper (to display interlaced screens correctly) coplist - copper list pointer, if NULL the old copper pointer remains NOTE This call is guaranteed to preserve all registers (except D0!!!) and is save to call from interrupts. SEE ALSO libraries/ros.i, ROSKillSystem() ros.library/ROSSetDMA ros.library/ROSSetDMA NAME ROSSetDMA -- modify DMA bits SYNOPSIS ROSSetDMA(DMACON) D0 VOID ROSSetDMA(UWORD); FUNCTION This function acts like a write to the DMACON register. Do NOT use "move.w #xxx,$dff096" !!!!!!! This may interfere with the system you are in non-deathmode, but ROSSetDMA() handles all exceptions correctly. DMA bit modification: - DMAF_BLTPRI: only in deathmode, but during a ROSSysCall() the system DMA bit will be restored - DMAF_DMAEN: same like BLTPRI - DMAF_BPLEN: only if ROS screen in front (non-os-friendly mode!) - DMAF_COPEN: same like BPLEN - DMAF_BLTEN: same like BLTPRI - DMAF_SPREN: same like BPLEN - DMAF_DSKEN: never modified!!! - DMAF_AUDxEN: only if audio channels allocated A currently forbidden DMA modification is automatically updated as soon as possible (e.g. bitplane DMA if ROS screen behind others). Closing the ros.library reset former system DMA. INPUTS DMACON - DMA bits NOTE This call is guaranteed to preserve all registers (except D0!!!) and is save to call from interrupts. SEE ALSO ROSGetDMA(), hardware/dmabits.i ros.library/ROSSetExitHandler ros.library/ROSSetExitHandler NAME ROSSetExitHandler -- add handler that is executed at exit key condition SYNOPSIS ROSSetExitHandler(handler); A0 VOID ROSSetExitHandler(APTR); FUNCTION Calling this routine causes the ROS to install an exit key conditon handler. Whenever this special key is pressed your handler is invoked (should be only once). Now it's time to finish your application. The routine is called from within an interrupt, so normal restrictions apply. On entry A5 holds the custom base ($dff000) and A6 holds _ROSBase. Your code may trash all registers. The default exit key code is ESC but may be changed in ros.prefs. --> New for V2: Now joyport events may also generate exit events if enabled via ROSSetJoyPortAttrs(). You should remove this handler with ROSSetExitHandler(NULL). Closing the ros.library removes this exit handler automatically. But remember: Exit conditions occurs only if you set the master interrupt bit via ROSSetInt(INTF_SETCLR|INTF_INTEN)! INPUTS handler - the routine to invoke upon exit key condition or NULL to detach the handler NOTE This call is guaranteed to preserve all registers (except A0!!!) and is save to call from interrupts. The handler may be called more than once if your application isn't fast enough to exit!!! SEE ALSO ros.library/ROSSetInt ros.library/ROSSetInt NAME ROSSetInt -- modify interrupt settings SYNOPSIS ROSSetInt(INTENA) D0 VOID ROSSetInt(UWORD); FUNCTION This function acts like a write to the INTENA register. Do NOT use "move.w #xxx,$dff09a" !!!!!!! This may interfere with the system if you are in non-deathmode, but ROSSetInt() handles all exceptions correctly. Only those bits are affected which belongs to previous ROSSetIntVec() calls. Look at ROSSetIntVec() for further information. In non-deathmode the master interrupt bit (INTB_INTEN) is emulated to support enable/disable of all ROS interrupts at once (system interrupts are still active!!!) Closing the ros.library reset former system interrupt bits. INPUTS INTENA - Int bits Note: level 1/2/5/6 bits (disk, serial, timer) are not supported!!! Instead additonal bits are defined: - KEYB - CIAATIMA/B - CIABTIMA/B Look at ROSSetIntVec() for further details NOTE This call is guaranteed to preserve all registers (except D0!!!). Do NOT call this routine from interrupts if you want to modify the CIA interrupts (CIAATIMA/B, CIABTIMA/B)!!!! SEE ALSO ROSGetInt(), ROSSetIntVec(), libraries/ros.i ros.library/ROSSetIntVec ros.library/ROSSetIntVec NAME ROSSetIntVec -- set a new handler for an interrupt vector SYNOPSIS success = ROSSetIntVec(intNum, handler) D0 D0 A0 BOOL ROSSetIntVec(UWORD, APTR); FUNCTION This function attaches a new handler to the interrupt specified with 'intNum'. Detach a handler with A0 = NULL. The routine is called from within an interrupt, so normal restrictions apply. On entry A5 holds the custom base ($dff000) and A6 holds _ROSBase. Your code may trash all registers. Your handler won't be invoked until you enable it (and the master int) via ROSSetInt(). After enabling your handler it's always invoked whether you taken over the systen or not. Interrupts are executed as follows: » INTB_BLIT - only in deathmode, during a ROSSysCall() the system routine will be restored so you do NOT use the blitter while the system is (partially) active - returncode is always TRUE » INTB_VERTB - always invoked, also without a call to ROSKillSystem() - in non-deathmode your vblank code may be called after display is started depending on the speed of higher prioritized vblank interrupts. If you want to synchronize custom chip modifications with the display you should use the copper. - but remember: in non-deathmode the vblank frequency may vary (not always 50Hz) if ROS screen behind others! - returncode is always TRUE » INTB_COPER - only if ROS screen in front - returncode is always TRUE » INTB_NMI (bit 15) - always invoked - returncode is always TRUE » INTB_AUD0..3 - only if channels allocated, else the returncode will be FALSE Further 5 new int definitions are supported: » INTB_CIAATIMA/CIAATIMB/CIABTIMA/CIABTIMB - used to attach a handler to the specified CIA timer - returncode may be FALSE if CIA allocation failed, in this case a Retry/Cancel-Requester appears (if not suppressed) - if returncode TRUE the specified timer bits are set to 0 (timer stopped) and now you may modify the contents of the CIA control register (CRA/CRB) - never read or write the CIA interrupt control register (ICR), use instead ROSSetInt() to enable/disble CIA interrupts!!!!!! » INTB_KEYB - used to track keyboard events (see also ROSGetKey()) - only invoked if ROS screen in front!!! - your handler is called with additional register D0 setup: * the lower word contains the keycode ($0..$67) with the additional key_up/down flag (bit7 set for key-up condition) * the upper word contains the qualifier bits (shift, alt, ...) - in non-deathmode it's up to you passing this key to other system components (like intuition.lib, commodities.lib, ...) * set the ZERO-flag at the end of your handler to pass the key to other system components, e.g. moveq #0,d0 * else clear the ZERO-flag, e.g. moveq #1,d0 * but remember: if you catch all key events screen switching and other system hotkeys dosn't work!!! * by default all keys without left-amiga or without control qualifiers are catched to prevent background menu activities and other undesirable things - returncode is always TRUE All other interrupt bits are NOT supported!!! Closing the ros.library detaches interrupt handlers automatically. INPUTS intnum - the Paula interrupt bit number (0 through 14). Processor level seven interrupts (NMI) are encoded as intNum 15. Note: level 1/2/5/6 bits (disk, serial, timer) are not supported!!! Instead additonal bits are defined: - KEYB - CIAATIMA/B - CIABTIMA/B handler - the routine to invoke or NULL to detach the handler RESULT success - TRUE if handler successfully attached NOTE This call is guaranteed to preserve all other registers. Do NOT call this routine from interrupts if you want to add a CIA handler for the first time!!! After a successful call you may change this vector with ROSSetIntVec() also from interrupts because the desired CIA is already allocated. SEE ALSO ROSSetInt(), ROSGetInt(), libraries/ros.i ros.library/ROSSetJoyPortAttrs ros.library/ROSSetJoyPortAttrs NAME ROSSetJoyPortAttrs -- change attributes of a joy port (V2) SYNOPSIS success = ROSSetJoyPortAttrs(portNumber, attribute); D0 D0 D1 BOOL ROSSetJoyPortAttrs(ULONG, ULONG); FUNCTION This function allows modification of several attributes held by ROSReadJoyPort() about both it's operation and the type of controller currently plugged into the port. ROSReadJoyPort()'s default behavior is to attempt to automatically sense the type of controller plugged into any given port, when asked to read that port. This causes most reads to take longer than if there were no auto-sensing. That's why ROSSetJoyPortAttrs() allows the programmer to notify ROSReadJoyPort() to stop spending time attempting to sense which type of controller is in use -- and, optionally, to force ROSReadJoyPort() into utilizing a certain controller type. This function is also used to turn on the rawkey code creation for the given port. This means ROSReadJoyPort() is called every frame to determine current port state and it's return values are converted into corresponding rawkey codes. To reduce the overhead caused by this attribute you should avoid the autosensing! ROS uses the same rawkey codes like lowlevel.library so look there (libraries/lowlevel.i) for further information. INPUTS portNumber - the joyport in question (0-3). attribute - one of the following attributes (from libraries/ros.i): » ROSJPA_AUTOSENSE - ROSReadJoyPort() will attempt to determine the type of controller plugged into the given port automatically - returns TRUE if port allocation succeeded » ROSJPA_MOUSE - sets current controller type to mouse - returns TRUE if port allocation succeeded » ROSJPA_JOYSTCK - sets current controller type to joystick - returns TRUE if port allocation succeeded » ROSJPA_GAMECTLR - sets current controller type to game controller - returns TRUE if port allocation succeeded » ROSJPA_ADDKEYS - starts creating rawkey codes for the joystick/game controller on the given unit, codes are passed to your keyboard-handler (see also ROSSetIntVec()) so the same restrictions apply: - only invoked if ROS screen in front!!! - your handler is called with additional register D0 setup: * the lower word contains the key code with additional key_up/down flag (bit7 set for key-up condition) * the upper word contains the qualifier bits - but: * these rawkey codes are NEVER passed to other system components (like intuition), only you will receive it! * in addition to the keyboard interrupt (INTB_INTEN/KEYB) the vblank interrupt (INTB_VERTB) must be active - NOTE (1): Now your keyboard-handler is also called from a level3 interrupt. That's why it must be reentrant!! (reason: joystick-movement (lev3) may interrupt a currently in-progress keypress-event (lev2)) - NOTE (2): Your handler may be called more than once per frame because multiple joy-movements generate multiple key codes! - NOTE (3): Now your exit-handler must also be reentrant because joyport events may generate exit events! - returns TRUE if port allocation succeeded » ROSJPA_REMKEYS - stops rawkey code creation on the given unit - returns always TRUE, whether port allocated or not!!! » ROSJPA_REINITIALIZE - return a given port to it's initial state: * set to autosense * stop rawkey code creation * deallocate resources - closing the ros.library reinitializes joy ports automatically - returns always TRUE, whether port allocated or not!!! RESULT success - TRUE if port allocation succeeded, or FALSE upon failure NOTE When called the first time, for each port, this function tries to allocate the desired port. Once it returns TRUE (except for ROSJPA_ REMKEYS/REINITIALIZE) the appropriate port is allocated and you may call ROSReadJoyPort() from interrupts. If allocation failed a Retry/Cancel-Requester appears to inform the user about the problem (if not suppressed and if not in deathmode) and this function will return FALSE. This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSReadJoyPort(), <libraries/lowlevel.i> ros.library/ROSSetTimerVec ros.library/ROSSetTimerVec NAME ROSSetTimerVec -- change the timer interrupt entry point SYNOPSIS ROSSetTimerVec(intRoutine, intHandle); A0 A1 VOID ROSSetTimerVec(APTR, ULONG); FUNCTION This routine changes the interrupt entry point that is assocatied with a timer interrupt created by ROSAddTimerInt(). No timer modification is done (no restart, no stop). The next interrupt will execute your new 'intRoutine'. INPUTS intRoutine - the routine to invoke upon timer interrupts. intHandle - handle obtained from ROSAddTimerInt(). NOTE This call is guaranteed to preserve all registers (except A1!!!) and is save to call from interrupts. SEE ALSO ROSAddTimerInt(), ROSRemTimerInt(), ROSStartTimer(), ROSStopTimer() ros.library/ROSStartTimer ros.library/ROSStartTimer NAME ROSStartTimer -- start the timer associated with the timer interrupt SYNOPSIS ROSStartTimer(timeInterval, continuous, intHandle); D0 D1 A1 VOID ROSStartTimer(ULONG, BOOL, ULONG); FUNCTION This routine starts a stopped timer that is assocatied with a timer interrupt created by ROSAddTimerInt(). But remember: Timer interupts occurs only if you set the master interrupt bit via ROSSetInt(INTF_SETCLR|INTF_INTEN)! INPUTS timeInterval - number of micoseconds between interrupts. The maximum value allowed is 90,000. If higher values are passed there will be unexpected results. continuous - FALSE for a one shot interrupt. TRUE for multiple interrupts. intHandle - handle obtained from ROSAddTimerInt(). NOTE This call is guaranteed to preserve register A0 and is save to call from interrupts. SEE ALSO ROSAddTimerInt(), ROSRemTimerInt(), ROSSetTimerVec(), ROSStopTimer() ros.library/ROSStopTimer ros.library/ROSStopTimer NAME ROSStopTimer -- stop the timer associated with the timer interrupt SYNOPSIS ROSStopTimer(intHandle); A1 VOID ROSStopTimer(ULONG); FUNCTION Stops the timer associated with the timer interrupt handle passed. This is used to stop a continuous timer started by ROSStartTimer(). INPUTS intHandle - handle obtained from ROSAddTimerInt() NOTE This call is guaranteed to preserve all registers (except A1!!!) and is save to call from interrupts. SEE ALSO ROSAddTimerInt(), ROSRemTimerInt(), ROSSetTimerVec(), ROSStartTimer() ros.library/ROSSysCall ros.library/ROSSysCall NAME ROSSysCall -- interrupts deathmode to enable system calls SYNOPSIS ROSSysCall() VOID ROSSysCall(VOID) FUNCTION This function provides a method to call system functions from within deathmode. YOU SHOULD NEVER NEED THIS FUNCTION! IT SHOULD BE A PRIVATE ROS CALL. DO NOT USE THIS CALL WITHOUT GOOD JUSTIFICATION. In order to restore normal deathmode, the programmer must execute exactly one call to ROSSysCallEnd() for every call to ROSSysCall(). During a SysCall all ROS interrupts continue executing (look at ROSSetIntVec() for details). But remember: system interrupts are also active and additional system DMA will be set! The blitter will be disowned so you do NOT bash the blitter until ROSSysCallEnd() is called. With ROS V2 WaitBlit() is also called before entering the system. Do NOT call system functions during a SysCall which may cause any visual modifications (like OpenScreen(), ScreenToBack(), ...). These functions will never return as long as the deathmode is the active one!!! Calling ROSSysCall() without a deathmode killed system is harmless. RESULT A partially active system. NOTE This call is guaranteed to preserve all registers. SEE ALSO ROSKillSystem(), ROSSetDMA(), ROSSetIntVec(), ROSSysCallEnd() ros.library/ROSSysCallEnd ros.library/ROSSysCallEnd NAME ROSSysCallEnd -- return from a SysCall SYNOPSIS ROSSysCallEnd() VOID ROSSysCallEnd(VOID) FUNCTION Call this function to return from a SysCall after a matching ROSSysCall() has been executed. RESULT A deathmode killed system. NOTE This call is guaranteed to preserve all registers. SEE ALSO ROSSysCall() ros.library/ROSWaitVBlank ros.library/ROSWaitVBlank NAME ROSWaitVBlank -- Wait for the vertical blank to occur SYNOPSIS ROSWaitVBlank() VOID ROSWaitVBlank(VOID); FUNCTION Waits for vertical blank to occur and than returns to the caller. --> New for V2: If not in real deathmode this function uses the graphics.library WaitTOF() call to ensure compatibility with foreign OS screens! NOTE This call is guaranteed to preserve all registers. This call does not require A6 to be loaded with the library base. BUGS Previous V1.xx documentation stated: "... and is save to call from interrupts." This is always wrong! Do NOT use this function from within interrupts! ros.library/ROSWriteFile ros.library/ROSWriteFile NAME ROSWriteFile -- Write a number bytes to a file SYNOPSIS actLength/errorcode = ROSWriteFile(flags, length, offset, name, buffer) D0 D1 D0 D1 D2 A0 A1 ULONG/ULONG ROSWriteFile(ULONG, ULONG, ULONG, STRPTR, VOID *); FUNCTION This function writes 'length' bytes to the file 'name' using dos.library's Write(). Set 'offset' to NULL to overwrite an existing file (file opened with MODE_NEWFILE). In the other case the data is written to the file 'name' with an 'offset' from the beginning (file opened with MODE_READWRITE). This can be used to append/replace data to/in an existing file. If the file doesn't exists or if filelength shorter than 'offset' a seek error occurs. A1 points to a buffer from where the data is taken from. Remember: On error a corrupt or a 0-byte-file may still exists!!! It's up to you to delete this. If ROSRWF_DISKWAIT flag set the routine assumes that you want to write 'name' to a floppy. This means: - waiting for the right disk to be inserted (implementation: DOS error codes DEVICE_NOT_MOUNTED, NOT_A_DOS_DISK, NO_DISK force retry until any other error occurs) --> New for V2: waiting may be cancelled via ROSDiskState() - waiting until disk drive stopped (implementation: polling disk.resource until drives are ready) Since OS2.0 it's possible to write files to your program path instead of the current directory using progdir:xxx. On OS1.3 the "progdir:" string is automatically removed by ROS so you don't have to worry about it. The only thing the user have to do is a "CD" to the program directory before starting (only on OS1.3). ;-) WARNING: It may be dangerous to use this routine within deathmode! Because of the AMIGA's multitasking facilities it isn't possible (isn't it???) to wait till the final end of a write operation. That's why I use a simple delay of 2 seconds after any write operation in deathmode. If your filesystem is to slow to write all the data within this time your partition will be NOT validated!!! You've been warned!!! INPUTS flags - use ROSRWF_DISKWAIT if you want to write to a floppy length - number of bytes to write offset - NULL for overwrite mode, else a number of bytes to skip before writing into an existing file name - pointer to a null-terminated string buffer - pointer to buffer where data is taken from RESULT actLength - number of bytes written or -1 if error errorcode - DOS error code on failure (may be NULL!!!) NOTE This function interrupts the deathmode state with ROSSysCall()! SEE ALSO ROSDeleteFile(), ROSDiskState(), dos.lib/Write()